ExtWebDropDown

Scoped name

WSYEXTJS/ExtWebDropDown

Purpose

This PageGenerator can be used to create a dynamically loaded drop down box.

This can be used when you have a maintenance page (e.g. an insert or and update page), where one of the fields are a reference to another entity. The drop down box will replace the input field, and the key of the selected record will be used as the value that will be sent to the EventHandler when the button assigned to the FORM is pressed.

Usage

In many cases, your entity will refer to other entities - e.g. using the refers to triple. When creating or updating your primary entity, you can in some cases let the user enter the foreign key manually - but in most cases this is not a good way to create the relation.

The ExtWebDropDown allows you to create a drop down box containing all the records from the referred entity. You can assign this function to the foreign key field and include or comprise it on your maintenance page to replace the input field for the foreign key with the drop down box.

The implementation has three steps:

1. Create the DropDown PageGenerator.
2. Assign the DropDown PageGenerator to the field.
3. Make the DropDown PageGenerator available for the maintenance page.

Creating the DropDown PageGenerator

Defining drop down content

Implementing the DropDownPageGenerator is just like implementing a standard ExtWebGridPage.

You must replace the UIBasic.Grid view with a function that defines the order of the records and you must replace the UIBasic.Grid.BlockFetch function with a function that inherits from either DataAccessRRN.Fetch.BlockFetchRRNWrapper or from RRNEntityRelationalTable.Fetch.WsyStatelessBlockFetchRRN.

This defines the content and order of the grid. If you have fields you do not want to show in the grid, you must add them to the OmitGridFields variable.

If more than one field is shown in the drop down box, a "-" character will be inserted between each field.

Defining the return value of the drop down

The aim of the drop down is to be able to select a value for a particular field. To make it possible for the Javascript functions to identify the value, you have to declare which field the drop down will return. This is done by adding the field to the local variable WsyReturnsValueOf:

The functionality only handles one field - if you add several fields to the local variable, only one will be returned to the page where you include the drop down.

Assign the DropDown PageGenerator to the field

The next step is to declare that the foreign key field can be populated using the drop down page. This is used by the new template generation to replace the input field of the foreign key with the drop down box.

This is done using the following triples (MyForeignKey is a Field object):

Make the DropDown PageGenerator available for the maintenance page

This last step enables the maintenance PageGenerator to call the DropDown PageGenerator as a child page. A JavaScript error will occur when the maintenance page is loaded if this step isn't performed and the foreign key is an input field on the maintenance page.

Alternatively, you can use the includes FNC triple.

Special considerations

Behavior of output fields with the special type triple

Event though the functionality described above is designed to be used for input fields, it has been requested that when a field has a "special type" triple as described above it should perform the same functionality for output fields. This means that when the field is used as an output field, it will be presented exactly as it is in the drop down - just without the option for selecting another value for the field.

To make this work, you must also define the comprises triple for pages where you have the field as an output field.

However, you should note that this also means that all the records that would be presented in the drop down box are fetched even though the field is an output field.

Behavior if the field is placed on a page without the comprises triple

If you have a field with a "special type" triple as described above on a page as either an input or an output field - but have not created the comprises triple to make the drop down available for the page - the field will always be presented as a textfield.

Load of data to the drop down

Note that the ExtWebDropDown function inherits from the ExtWebGridPage function. This means that the special behavior for loading a list of records that is described for the ExtWebGridPage also is used for functions inheriting from ExtWebDropDown.

When to use a drop down for selection

Before using a drop down box to create a reference to another entity, you should always consider the number of records in the referred entity. The drop down box always perform a full-load of the grid, which can cause problems if there are many records in the referred entity.

As mentioned above, the functionality described here can only be used for entities where the record can be uniquely identified by one field.

More information

• The new template generation explained.
• The Ext JS framework for WebsydianExpress explained.
• Loading a grid page in the Ext JS framework
• BlockFetchRRNWrapper
• WsyStatelessBlockFetchRRN